create-cluster(1)         asadmin Utility Subcommands        create-cluster(1)

NAME
       create-cluster - creates a GlassFish Server cluster

SYNOPSIS
           create-cluster [--help] [--config config-name]
           [--systemproperties (name=value)[:name=value]*]
           [--properties (name=value)[:name=value]*]
           [--gmsenabled={true|false}]
           [--multicastport multicast-port]
           [--multicastaddress multicast-address]
           [--bindaddress bind-address]
           [--hosts hadb-host-list]
           [--haagentport port-number]
           [--haadminpassword password]
           [--haadminpasswordfile file-name] [--devicesize devicesize ]
           [--haproperty (name=value)[:name=value]*]
           [--autohadb=false] [--portbase port-number]
           cluster-name

DESCRIPTION
       The create-cluster subcommand creates a GlassFish Server cluster.
       Initially the cluster contains no GlassFish Server instances,
       applications, or resources.

       A cluster requires a reference to the named configuration that defines
       the configuration of all instances that are added to the cluster. The
       configuration can be specified in the command to create the cluster,
       but is not required. If no configuration is specified, the subcommand
       creates a configuration that is named cluster-name-config for the
       cluster. The cluster that is created is a standalone cluster because
       the cluster's configuration is not shared with any other clusters or
       standalone instances.

       To add instances to the cluster, set the --cluster option to the name
       of the cluster when using either of the following subcommands:

       *   create-instance(1)

       *   create-local-instance(1)

       To delete server instances from the cluster at any time, use one of the
       following subcommands:

       *   delete-instance(1)

       *   delete-local-instance(1)

       To associate applications and resources with all instances in the
       cluster, set the --target option to the name of the cluster when
       performing the following operations:

       *   Deploying applications by using the deploy(1) subcommand

       *   Creating resources by using subcommands such as
           create-jdbc-resource(1)

       *   Creating references to applications that are already deployed in
           other targets by using the create-application-ref(1) subcommand

       *   Creating references to resources that are already created in other
           targets by using the create-resource-ref(1) subcommand

       This subcommand is supported in remote mode only.

OPTIONS
       --help, -?
           Displays the help text for the subcommand.

       --config
           Specifies the named configuration that the cluster references. The
           configuration must exist and must not be named default-config or
           server-config. Specifying the --config option creates a shared
           cluster. If this option is omitted, a standalone cluster is
           created.

       --systemproperties
           Defines system properties for the configuration that is created for
           the cluster. These properties override the property values in the
           default-config configuration. The following properties are
           available:

           ASADMIN_LISTENER_PORT
               This property specifies the port number of the HTTP port or
               HTTPS port through which the DAS connects to the instance to
               manage the instance. Valid values are 1-65535. On UNIX,
               creating sockets that listen on ports 1-1024 requires superuser
               privileges.

           HTTP_LISTENER_PORT
               This property specifies the port number of the port that is
               used to listen for HTTP requests. Valid values are 1-65535. On
               UNIX, creating sockets that listen on ports 1-1024 requires
               superuser privileges.

           HTTP_SSL_LISTENER_PORT
               This property specifies the port number of the port that is
               used to listen for HTTPS requests. Valid values are 1-65535. On
               UNIX, creating sockets that listen on ports 1-1024 requires
               superuser privileges.

           IIOP_LISTENER_PORT
               This property specifies the port number of the port that is
               used for IIOP connections. Valid values are 1-65535. On UNIX,
               creating sockets that listen on ports 1-1024 requires superuser
               privileges.

           IIOP_SSL_LISTENER_PORT
               This property specifies the port number of the port that is
               used for secure IIOP connections. Valid values are 1-65535. On
               UNIX, creating sockets that listen on ports 1-1024 requires
               superuser privileges.

           IIOP_SSL_MUTUALAUTH_PORT
               This property specifies the port number of the port that is
               used for secure IIOP connections with client authentication.
               Valid values are 1-65535. On UNIX, creating sockets that listen
               on ports 1-1024 requires superuser privileges.

           JAVA_DEBUGGER_PORT
               This property specifies the port number of the port that is
               used for connections to the Java Platform Debugger Architecture
               (JPDA)

               (http://www.oracle.com/technetwork/java/javase/tech/jpda-141715.html)

               debugger. Valid values are 1-65535. On UNIX, creating sockets
               that listen on ports 1-1024 requires superuser privileges.

           JMS_PROVIDER_PORT
               This property specifies the port number for the Java Message
               Service provider. Valid values are 1-65535. On UNIX, creating
               sockets that listen on ports 1-1024 requires superuser
               privileges.

           JMX_SYSTEM_CONNECTOR_PORT
               This property specifies the port number on which the JMX
               connector listens. Valid values are 1-65535. On UNIX, creating
               sockets that listen on ports 1-1024 requires superuser
               privileges.

           OSGI_SHELL_TELNET_PORT
               This property specifies the port number of the port that is
               used for connections to the Apache Felix Remote Shell

               (http://felix.apache.org/site/apache-felix-remote-shell.html) .
               This shell uses the Felix shell service to interact with the
               OSGi module management subsystem. Valid values are 1-65535. On
               UNIX, creating sockets that listen on ports 1-1024 requires
               superuser privileges.

       --properties
           Defines properties for the cluster. The following properties are
           available:

           GMS_DISCOVERY_URI_LIST
               The locations of GlassFish Server instances in the cluster to
               use for discovering the cluster. This property is required only
               if the Group Management Service (GMS) is not using multicast
               for broadcasting messages.

               Valid values for this property are as follows:

               *   A comma-separated list of uniform resource identifiers
                   (URIs). Each URI must locate a GlassFish Server instance or
                   the DAS. This format is required if multiple GlassFish
                   Server instances are running on the same host.

                   The format of each URI in the list is as follows:

                   scheme://host-name-or -IP-address:port

                   *   scheme is the URI scheme, which is tcp.

                   *   host-name-or -IP-address is the host name or IP address
                       of the host on which the instance is running.

                   *   port is the port number of the port on which the
                       instance listens for messages from GMS. The system
                       property GMS_LISTENER_PORT-clustername must be set for
                       the instance. For information about how to set this
                       system property for an instance, see "Discovering a
                       Cluster When Multicast Transport Is Unavailable" in
                       Oracle GlassFish Server High Availability
                       Administration Guide.

               *   A comma-separated list of IP addresses or host names on
                   which the DAS or the instances are running. The list can
                   contain a mixture of IP addresses and host names. This
                   format can be used only if one clustered instance is
                   running on each host. The value of the GMS_LISTENER_PORT
                   property must be unique for each cluster in a domain.

               *   The keyword generate. This format can be used only if one
                   instance in a cluster is running on each host and the DAS
                   is running on a separate host. Multiple instances on the
                   same host cannot be members of the same cluster. The value
                   of the GMS_LISTENER_PORT property must be unique for each
                   cluster in a domain.

           GMS_LISTENER_PORT
               The port number of the port on which the cluster listens for
               messages from GMS.

               The default value is a reference to the
               GMS_LISTENER_PORT-cluster-name system property. By default,
               this system property is not set. In this situation, GMS selects
               a free port from the range that is defined by the properties
               GMS_TCPSTARTPORT and GMS_TCPENDPORT. By default, this range is
               9090-9200. In most situations, the default behavior should
               suffice.

               However, if GMS is not using multicast for broadcasting
               messages, the GMS_LISTENER_PORT property must specify a port
               number that is valid for all GlassFish Server instances in the
               cluster. To use the default value to meet this requirement, use
               a system property to set the port number individually for each
               instance.

               For example, use the create-system-properties subcommand to
               create the system property GMS_LISTENER_PORT-cluster-name for
               the DAS. Then, for each instance in the cluster, set the
               GMS_LISTENER_PORT-cluster-name system property to the port
               number on which the instance listens for messages from GMS. The
               default value of the GMS_LISTENER_PORT property for the cluster
               references this system property.

           GMS_LOOPBACK
               Specifies whether an instance may receive from itself
               application-level messages that the instance broadcasts to the
               cluster.

               Possible values are as follows:

               false
                   The instance may not receive messages from itself
                   (default).

               true
                   The instance may receive messages from itself. Use this
                   setting for testing an instance when the instance is the
                   only instance in a cluster.

           GMS_MULTICAST_TIME_TO_LIVE
               The maximum number of iterations or transmissions that a
               multicast message for the following types of events can
               experience before the message is discarded:

               *   Group discovery

               *   Member heartbeats

               *   Membership changes

               To match the configuration of the network on which the DAS and
               clustered instances are deployed, set this value as low as
               possible. To determine the lowest possible value for your
               system, use the validate-multicast(1) subcommand.

               A value of 0 ensures that multicast messages never leave the
               host from which they are broadcast.

               A value of 1 might prevent the broadcast of messages between
               hosts on same subnet that are connected by a switch or a
               router.

               The default is 4, which ensures that messages are successfully
               broadcast to all cluster members in networks where hosts are
               connected by switches or routers.

           GMS_TCPENDPORT
               The highest port number in the range from which GMS selects a
               free port if the GMS_LISTENER_PORT-cluster-name system property
               is not set. The default is 9200.

           GMS_TCPSTARTPORT
               The lowest port number in the range from which GMS selects a
               free port if the GMS_LISTENER_PORT-cluster-name system property
               is not set. The default is 9090.

       --gmsenabled
           Specifies whether GMS is enabled for the cluster.

           Possible values are as follows:

           true
               GMS is enabled for the cluster (default).

               When GMS is enabled for a cluster, GMS is started in each
               server instance in the cluster and in the DAS. The DAS
               participates in each cluster for which this option is set to
               true.

           false
               GMS is disabled for the cluster.

       --multicastaddress
           The address on which GMS listens for group events. This option must
           specify a multicast address in the range 224.0.0.0 through
           239.255.255.255. The default is 228.9.XX.YY, where XX and YY are
           automatically generated independent values between 0 and 255.

       --multicastport
           The port number of communication port on which GMS listens for
           group events. This option must specify a valid port number in the
           range 2048-49151. The default is an automatically generated value
           in this range.

       --bindaddress
           The Internet Protocol (IP) address of the network interface to
           which GMS binds. This option must specify the IP address of a local
           network interface. The default is all public network interface
           addresses.

           On a multihome machine, this option configures the network
           interface that is used for the GMS. A multihome machine possesses
           two or more network interfaces.

           To specify an address that is valid for all GlassFish Server
           instances in the cluster, use a system property to set the address
           individually for each instance.

           For example, use the create-system-properties subcommand to create
           the system property GMS-BIND-INTERFACE-ADDRESS-cluster-name. Then
           set the --bindaddress option of this subcommand to
           ${GMS-BIND-INTERFACE-ADDRESS-cluster-name} to specify the system
           property. Finally, for each instance in the cluster, set the
           GMS-BIND-INTERFACE-ADDRESS-cluster-name system property to the
           required network interface address on the instance's machine.

       --hosts
           Do not specify this option. This option is retained for
           compatibility with earlier releases. If you specify this option, a
           syntax error does not occur. Instead, the subcommand runs
           successfully and displays a warning message that the option is
           ignored.

       --haagentport
           Do not specify this option. This option is retained for
           compatibility with earlier releases. If you specify this option, a
           syntax error does not occur. Instead, the subcommand runs
           successfully and displays a warning message that the option is
           ignored.

       --haadminpassword
           Do not specify this option. This option is retained for
           compatibility with earlier releases. If you specify this option, a
           syntax error does not occur. Instead, the subcommand runs
           successfully and displays a warning message that the option is
           ignored.

       --haadminpasswordfile
           Do not specify this option. This option is retained for
           compatibility with earlier releases. If you specify this option, a
           syntax error does not occur. Instead, the subcommand runs
           successfully and displays a warning message that the option is
           ignored.

       --devicesize
           Do not specify this option. This option is retained for
           compatibility with earlier releases. If you specify this option, a
           syntax error does not occur. Instead, the subcommand runs
           successfully and displays a warning message that the option is
           ignored.

       --haproperty
           Do not specify this option. This option is retained for
           compatibility with earlier releases. If you specify this option, a
           syntax error does not occur. Instead, the subcommand runs
           successfully and displays a warning message that the option is
           ignored.

       --autohadb
           Do not specify this option. This option is retained for
           compatibility with earlier releases. If you specify this option, a
           syntax error does not occur. Instead, the subcommand runs
           successfully and displays a warning message that the option is
           ignored.

       --portbase
           Do not specify this option. This option is retained for
           compatibility with earlier releases. If you specify this option, a
           syntax error does not occur. Instead, the subcommand runs
           successfully and displays a warning message that the option is
           ignored.

OPERANDS
       cluster-name
           The name of the cluster.

           The name must meet the following requirements:

           *   The name may contain only ASCII characters.

           *   The name must start with a letter, a number, or an underscore.

           *   The name may contain only the following characters:

               *   Lowercase letters

               *   Uppercase letters

               *   Numbers

               *   Hyphen

               *   Period

               *   Underscore

           *   The name must be unique in the domain and must not be the name
               of another cluster, a named configuration, a GlassFish Server
               instance, or a node.

           *   The name must not be domain, server, or any other keyword that
               is reserved by GlassFish Server.

           If the configure-jms-cluster(1) subcommand is to be used to
           configure a Message Queue cluster to provide JMS services to the
           GlassFish Server cluster, the length of the GlassFish Server
           cluster name is might be restricted:

           *   If clustertype is set to enhanced in the
               configure-jms-cluster(1) subcommand, the name can be no longer
               than n–21 characters, where n is the maximum table name length
               allowed by the database.

           *   If configstoretype is set to shareddb in the
               configure-jms-cluster(1) subcommand, the name can be no longer
               than n–19 characters, where n is the maximum table name length
               allowed by the database.

EXAMPLES
       Example 1, Creating a Cluster
           This example creates a cluster that is named ltscluster for which
           port 1169 is to be used for secure IIOP connections. Because the
           --config option is not specified, the cluster references a copy of
           the named configuration default-config that is named
           ltscluster-config.

               asadmin> create-cluster
               --systemproperties IIOP_SSL_LISTENER_PORT=1169
               ltscluster
               Command create-cluster executed successfully.

       Example 2, Creating a Cluster With a List of URIs for Discovering the
       Cluster
           This example creates a cluster that is named tcpcluster. In this
           example, GMS is not using multicast for broadcasting messages and
           multiple instances reside on the same host. Therefore, the
           GMS_DISCOVERY_URI_LIST property is set to the locations of the
           GlassFish Server instances to use for discovering the cluster.
           These instances reside on the host whose IP address is
           10.152.23.224 and listen for GMS events on ports 9090, 9091, and
           9092.

           To distinguish colon (:) characters in URIs from separators in a
           property list, colons in URIs are escaped with single quote
           characters (') and backslash (\) characters. For more information
           about escape characters in options for the asadmin utility, see the
           asadmin(1M) help page.

           This example assumes that the port on which each instance listens
           for GMS messages is set independently for the instance through the
           GMS_LISTENER_PORT-tcpcluster system property. For information about
           how to set the port on which an instance listens for GMS messages,
           see "Discovering a Cluster When Multicast Transport Is Unavailable"
           in Oracle GlassFish Server High Availability Administration Guide.

               asadmin> create-cluster --properties GMS_DISCOVERY_URI_LIST=
               tcp'\\:'//10.152.23.224'\\:'9090,
               tcp'\\:'//10.152.23.224'\\:'9091,
               tcp'\\:'//10.152.23.224'\\:'9092 tcpcluster
               Command create-cluster executed successfully.

       Example 3, Creating a Cluster With a List of IP Addresses for
       Discovering the Cluster
           This example creates a cluster that is named ipcluster. In this
           example, GMS is not using multicast for broadcasting messages and
           only one clustered instance resides on each host. Therefore, the
           GMS_DISCOVERY_URI_LIST property is set to the IP addresses of the
           hosts where instances to use for discovering the cluster are
           running. The cluster listens for messages from GMS on port 9090.

               asadmin> create-cluster --properties 'GMS_DISCOVERY_URI_LIST=
               10.152.23.225,10.152.23.226,10.152.23.227,10.152.23.228:
               GMS_LISTENER_PORT=9090' ipcluster
               Command create-cluster executed successfully.

       Example 4, Creating a Cluster With a Generated List of Instances for
       Discovering the Cluster
           This example creates a cluster that is named gencluster. In this
           example, GMS is not using multicast for broadcasting messages, one
           instance in the cluster is running on each host and the DAS is
           running on a separate host. Therefore, the GMS_DISCOVERY_URI_LIST
           property is set to the keyword generate to generate a list of
           instances to use for discovering the cluster. The cluster listens
           for messages from GMS on port 9090.

               asadmin> create-cluster --properties 'GMS_DISCOVERY_URI_LIST=generate:
               GMS_LISTENER_PORT=9090' gencluster
               Command create-cluster executed successfully.

EXIT STATUS
       0
           command executed successfully

       1
           error in executing the command

SEE ALSO
       create-application-ref(1), create-instance(1), create-jdbc-resource(1),
       create-local-instance(1), create-resource-ref(1), delete-cluster(1),
       delete-instance(1), delete-local-instance(1), deploy(1),
       list-clusters(1), start-cluster(1), stop-cluster(1),
       validate-multicast(1)

       asadmin(1M)

       "Discovering a Cluster When Multicast Transport Is Unavailable" in
       Oracle GlassFish Server High Availability Administration Guide

       Apache Felix Remote Shell
       (http://felix.apache.org/site/apache-felix-remote-shell.html), Java
       Platform Debugger Architecture (JPDA)
       (http://www.oracle.com/technetwork/java/javase/tech/jpda-141715.html)

Java EE 8                         21 Aug 2017                 create-cluster(1)
